@database "PicIcon.guide"
@version "$VER: PicIcon 1.03 ( 28.02.94 ) "
@master "PicIcon.doc"
@Author "Michael J. Sheppard"
@node Main "PicIcon 1.03"
@next Introduction
               @{b}PicIcon 1.03 - Icon Image Generator@{ub}
Table of Contents
   @{"Introduction"    link Introduction}
   @{"Copyright"       link Copyright   }
   @{"Using PicIcon"   link Operation   }
   @{"Hints and Tips"  link hints       }
   @{"Note for Workbench 3.0" link wb3  }
   @{"Limitations"     link limits      }
   @{"Bug reports"     link bugs        }
   @{"Change History"  link history     }
   @{"Acknowledgments" link ack         }   
      
@endnode
@node Introduction "PicIcon: Introduction"
@next Copyright
@prev Main
PicIcon takes an IFF image file, both ILBM and ANIM formats are supported,
and creates an icon image showing the contents of the file. This allows
images to be more easily recognised from the Amiga Workbench.
PicIcon be used from both the CLI and Workbench, although it is more suited
to the Workbench environment with some functions only being available via
Workbench.
PicIcon is distributed as shareware. This version is fully functional
however a requester saying that is not registered will appear after
a number of files have been processed. See the copyright section for
details on how to register.
PicIcon requires AmigaDOS 2.04 (V37) or later to run.
@endnode
@node Copyright "PicIcon: Copyright"
@next Operation
@prev Introduction
                  PicIcon release 1.03
PicIcon 1.03 and PicIcon project icon (hereinafter "Files") and
their related documentation and examples
(c) Copyright 1994 Michael J. Sheppard. All Rights Reserved.
This version of PicIcon is shareware. Permission is given to distribute
these Files freely via any means which preserves its copyrights. The
Files may not be sold for profit. Any distribution must include both
the PicIcon License file and the PicIcon documentation drawer complete
with contents.
The registered version of PicIcon contains the full source code and
removes the shareware message from it's operation. To register send
10 UK pounds, or $15 US, to ;
   PicIcon Registration.
   M.J.Sheppard
   163, Sapgate Lane,
   Thornton
   Bradford
   BD13 3DY
If you include an Internet email address with your registration then I
will keep you informed of updates to PicIcon and their availability. 
These Files and their related documentation and examples are provided
"AS-IS" and subject to change without notice; no warranties are made.
All use is at your own risk. No liability or responsibility is
assumed.
@endnode
@node Operation "Using PicIcon"
@prev Copyright
@next hints
PicIcon can be started from either the @{"Workbench" link WBStart} or @{"CLI" link CLIStart}.
PicIcon has two modes of operation. It can either try and match the colours
in the file with those currently in use by Workbench, or just assign colours
on a modular basis i.e. Areas in colour 1 in the file appear as colour 1 in
the icon. For any file whose image has greater than 256 colours PicIcon will
always try to match the colours. For images with fewer than 256 colours the
method used can be set by the user via the @{"match colours" link sw_match } checkbox
on the @{"settings window" link set_window}.
When matching colours PicIcon looks for the nearest colour based on colour
intensity. This can result is some unexpected colour choices. For example
for a greyscale image PicIcon may introduce some colour in the icon this is
because there aren't enough greys in the Workbench palette to match all of
the colours to a grey. More information about PicIcons colour matching can
be found in the @{"Hints and Tips" link hints} section of this document.
@endnode
@node WBStart "PicIcon: Workbench Startup"
To start PicIcon from Workbench double-click on the PicIcon icon with the
left mouse button. After a few seconds an application icon will appear on
the Workbench. 
PicIcon recognises an number of tooltypes to modify it's operation:   
   @{"SETTINGS" link wb_settings }
   @{"WIDTH"    link wb_width    }
   @{"HEIGHT"   link wb_height   }
   @{"DEPTH"    link wb_depth    }
   @{"QUIET"    link wb_quiet    }
   @{"FONT"     link wb_font     }
   @{"FONTSIZE" link wb_fontsize }
To create an image drag the icon of a file onto the application icon and
release the mouse button. PicIcon will then process the file and create
an icon image.
If you double-click on the application icon a @{"window" link set_window} is displayed allowing
you to change the current settings used to create icons.
To stop PicIcon either double-click on the PicIcon disk icon, or select the
@{"quit" link sm_quit} item on the @{"settings menu bar" link set_menu}.
@endnode
@node wb_settings "PicIcon: Settings tooltype"
@prev Operation
@next wb_width
SETTINGS=<filename>
This is the name of a file containing PicIcon settings to use
when processing the files. New settings files can be created
using the @{"Settings window" link set_window}.
If this parameter is not present then PicIcon will load the
default settings file, S:PicIcon.config.
@endnode
@node wb_width "PicIcon: Width tooltype"
@prev wb_settings
@next wb_height
WIDTH=<pixels>
This is the width, in pixels, of the icons created by PicIcon.
This value overrides the value stored in the settings file. 
Default = 48
@endnode
@node wb_height "PicIcon: Height tooltype"
@prev wb_width
@next wb_depth
HEIGHT=<pixels>
This is the height, in pixels, of the icons created by PicIcon.
This value overrides the value stored in the settings file.
Default = 20
@endnode
@node wb_depth "PicIcon: Depth tooltype"
@prev wb_height
@next wb_quiet
DEPTH=<planes>
This is the depth, in planes, of the icons created by PicIcon.
This value overrides the value stored in the settings file.
This effects the number of colours used in the icons and can
be 2, 3 or 4 for 4, 8 or 16 colours respectively.
Default = 3 ( 8 colours ).
@endnode
@node wb_quiet "PicIcon: Quiet tooltype"
@prev wb_depth
@next wb_font
QUIET
By default PicIcon displays a window showing the progress is it
making processing each file. This option stops this window appearing.
This can be overridden using the Quiet option on the Settings menu.
@endnode
@node wb_font "PicIcon: Font tooltype"
@prev wb_quiet
@next wb_fontsize
FONT <name>
PicIcon uses the system default font for all windows. This option
allows you to specify a particular font to use for the windows.
The @{"FONTSIZE" link wb_fontsize} tooltype should be used to set the
size of the font.
@endnode
@node wb_fontsize "Picicon: Fontsize tooltype"
@next CLIStart
@prev wb_font
                        
FONTSIZE <pixels>
This tooltype allows you to set the size of the font given in the
@{"FONT" link wb_font} tooltype.
@endnode
@node CLIStart "PicIcon: CLI Startup"
PicIcon processes all of the files listed on the command line and exits.
If an error is detected when processing a file then PicIcon will continue
to the next file if possible.
The command template for PicIcon is as follows;
PicIcon @{"FILES/M" link cli_files},@{"SETTINGS/K" link cli_settings},@{"WIDTH/K/N" link cli_width},@{"HEIGHT/K/N" link cli_height},@{"DEPTH/K/N" link cli_depth},@{"QUIET/S" link cli_quiet},@{"ALL/S" link cli_all}
@endnode
@node cli_files "PicIcon: Files parameter"
@next cli_settings
@prev CLIStart
FILES/M
A list of files to create icon images for. if this is an AmigaDOS pattern
PicIcon will process all files that match the pattern.
                  
      PicIcon  #?.ham
                     
      Will create icon images for all files in the current drawer having
      names ending in '.ham'.
@endnode
@node cli_settings "PicIcon: Settings parameter"
@prev cli_files
@next cli_width
SETTINGS/K
This is the name of a file containing PicIcon settings to use
when processing the files. New settings files can be created
using the @{"Settings window" link set_window}.
If this parameter is not present then PicIcon will load the
default settings file, S:PicIcon.config.
@endnode
@node cli_width "PicIcon: Width parameter"
@prev cli_settings
@next cli_height
WIDTH/K/N
This is the width, in pixels, of the icons created by PicIcon.
This value overrides the value stored in the settings file. 
Default = 48
@endnode
@node cli_height "PicIcon: Height parameter"
@prev cli_width
@next cli_depth
HEIGHT/K/N
This is the height, in pixels, of the icons created by PicIcon.
This value overrides the value stored in the settings file.
Default = 20
@endnode
@node cli_depth "PicIcon: Depth parameter"
@prev cli_height
@next cli_quiet
DEPTH/K/N
This is the depth, in planes, of the icons created by PicIcon.
This value overrides the value stored in the settings file.
This effects the number of colours used in the icons and can
be 2, 3 or 4 for 4, 8 or 16 colours respectively.
Default = 3 ( 8 colours ).
Note: Under Workbench 3.0 the choice of icon depth is limited
      to 2 or 3 giving 4 or 8 colours only. This is due to the
      change in colour handling introduced for Workbench 3.0.
@endnode
@node cli_quiet "PicIcon: Quiet parameter"
@next cli_all
@prev cli_depth
QUIET
By default PicIcon displays the names of the files as it processes them.
Setting this flag stops PicIcon from displaying this information.
@endnode
@node cli_all "PicIcon: All parameter"
@next hints
@prev cli_quiet
This flag causes PicIcon to process all of the files in the directories
specified in the @{"FILES" link cli_files} argument, including any subdirectories that 
they might have.   
@endnode
@node set_window "PicIcon: Settings Window"
@prev WBStart
@next set_menu
The settings window allows you to modify the current settings used to create
icon images. It is activated by double-clicking on the PicIcon application
icon. The effects of the changes are controlled by the three buttons at the
bottom of the window, @{ "Save" link sw_save }, @{ "Use" link sw_use }, and @{ "Cancel" link sw_cancel }. No changes made to the window
will have any effect on the creation of images until one of these three
buttons is pressed.
The settings that can be changed from this window are ;
   @{"Width" link sw_width }             The width of the icon in pixels
   @{"Height" link sw_height }            The height of the icon in pixels
   @{"Colours" link sw_colour }           The number of colours in the icon
   @{"Border" link sw_border }            Whether the icon should have a border
   @{"Match Colours" link sw_match }     Whether PicIcon should match image/workbench colours
   @{"Free Position" link sw_free }     Whether PicIcon should free the icon position
   @{"Replace Tool" link sw_free }      Whether PicIcon should set the icon default tool
   @{"Default Tool" link sw_deftool }      The default tool PicIcon should give icons
   @{"Tool types" link sw_tool }        The Tool types to use with the default tool
As well as displaying the window a @{"menu bar" link set_menu } is installed allowing you
to load and save settings and quit PicIcon.
@endnode
@node sw_width "PicIcon: Settings window - Width"
@prev set_window
@next sw_height
Gadget Type  : Slider   
Value range  : 20 - 80 pixels
Shortcut key : w
This gadget allows you to change the width of the icons produced. When making
changes to the dimensions of the icon you should consider the dimensions of
the original image to limit to amount of distortion in the resultant icon.
@endnode
                        
@node sw_height "PicIcon: Settings window - Height"
@prev sw_width
@next sw_colour
Gadget Type  : Slider   
Value range  : 10 - 40 pixels
Shortcut key : h
This gadget allows you to change the height of the icons produced. When making
changes to the dimensions of the icon you should consider the dimensions of
the original image to limit to amount of distortion in the resultant icon.
@endnode
@node sw_colour "PicIcon: Settings window - Colours"      
@prev sw_height
@next sw_border
Gadget Type  : Slider   
Value range  : 4,8, or 16* colours
Shortcut key : l
This gadget allows you to change the number of colours in the resultant icon
image. When selecting this bear in mind the number of colours that you normally
use for your Workbench screen.
*: Under Workbench 3.0 the option for 16 colours is not available.
@endnode
@node sw_border "PicIcon: Settings window - Border"
Gadget Type  : Checkbox
Shortcut key : b
If this is checked then PicIcon will draw a box around the resultant image
making it appear that icon has a border around it. PicIcon takes advantage
of the Workbench 3D icons to produce a border with a minimum loss of image.
@endnode
@node sw_match "PicIcon: Settings window - Match Colours"
@prev sw_border
@next sw_free
Gadget Type  : Checkbox
Shortcut key : m
If this gadget is checked then PicIcon will attempt to match the colours in
the image to those currently in use by Workbench. For images with more than
256 colours PicIcon ignores this and matches the colours anyway.
@endnode
@node sw_free "PicIcon: Settings window - Free Position"
@prev sw_match
@next sw_replace
Gadget Type  : Checkbox
Shortcut key : p
If this box is checked then PicIcon 'UnSnapshots' the icon allowing
Workbench to position it appropriately. This is useful if the size
of the icon is changed.
@endnode
@node sw_replace "PicIcon: Settings window - Replace Tool"
@prev sw_match
@next sw_deftool
Gadget Type  : Checkbox
Shortcut key : r
If this gadget is checked, and a default tool is given, PicIcon will
replace the default tool in the icon with that defined. Otherwise
PicIcon will only replace the default tool if the icon previously had
no tool defined.
@endnode
@node sw_deftool "PicIcon: Settings window - Default Tool"
@prev sw_replace
@next sw_tool
Gadget Type  : String
Maximum size : 128 characters
Shortcut key : t
This string is the name of the program to execute when the icon created
is double clicked. How the value is used depends on the setting of the
@{ "Replace Tool" link sw_replace }  gadget.
@endnode
@node sw_tool "PicIcon: Settings window - Tooltypes"
@prev sw_deftool
@next sw_new
Gadget Type  : Listview
Shortcut key : none
The tooltypes used when creating an icon are displayed in the listview gadget,
these are only used when PicIcon sets the default tool of the icon it has
created an image for.
It is not possible to edit the values in the listview directly so this has to
be done using the @{"New" link sw_new} and @{"Del" link sw_del} gadgets. These allow tooltypes to be added and
deleted from the list respectively.
@endnode
@node sw_new "PicIcon: Settings window - New"
@next sw_del
@prev sw_tool
Gadget Type  : Button
Shortcut key : n
Pressing this button adds a new tooltype to the list of tooltypes. It allows
you to type in the value of this tooltype into the string gadget to the left
of the New and @{"Del" link sw_del } buttons. Each tooltype can be up to 128
characters long.
@endnode
@node sw_del "PicIcon: Settings window - Del"
@next sw_save
@prev sw_new
Gadget Type  : Button
Shortcut key : d
Pressing this button deletes the currently selected tooltype from the list
of tooltypes. This button is only enabled if you have a tooltype selected.
@endnode
@node sw_save "PicIcon: Settings window - Save button"
@next sw_use
@prev sw_del
Gadget Type  : Button
Shortcut key : s
This button causes the settings in the window to be made the current
ones used by the program and saves those settings to the default settings
file. It also exits from the settings window.
@endnode
@node sw_use "PicIcon: Settings window - Use button"
@next sw_cancel
@prev sw_save
Gadget Type  : Button
Shortcut key : u
This button exits from the settings window and makes the settings displayed
in the window the current settings.
@endnode
@node sw_cancel "PicIcon: Settings window - Cancel button"
@next set_menu
@prev sw_use
Gadget Type  : Button
Shortcut key : c
     
When this button is pressed the settings window is removed and all changes
made are abandoned.
@endnode
@node set_menu "PicIcon: Settings Menu"
@prev set_window
@next hints
   Whilst the window is active PicIcon installs a menu bar allowing a number
   of extra features to be selected.
   Project menu
   @{"Create Icon" link sm_create }
   @{"About" link sm_about }
   @{"Quit" link sm_quit }
      
   Settings menu
   @{"Quiet" link sm_quiet }
   @{"Load Settings" link sm_quiet }
   @{"Save Settings" link sm_save }
   @{"Save Settings As" link sm_saveas }
@endnode
@node sm_create "PicIcon: Settings Menu - Create Icon"
@prev set_menu
@next sm_about
Shortcut Key: Amiga C
The option displays an ASL file requester allowing you to select a number
of files to create icons for. Selecting the OK button on the file requester
causes PicIcon to process all of the files selected.
If changes have been made to the values in the @{"settings window" link set_window } they are not
taken into account when creating the new images.
@endnode
@node sm_about "PicIcon: Settings Menu - About"
@next sm_quit
@prev sm_create
Shortcut key: Amiga ?
A requester is displayed showing information about PicIcon. This includes the
version number of the PicIcon being run.
@endnode
@node sm_quit "PicIcon: Settings Menu - Quit"
@next sm_quiet
@prev sm_about
Shortcut key: Amiga Q
Selecting this menu option causes PicIcon to exit.
@endnode
@node sm_quiet "PicIcon: Settings Menu - Quiet"
@next sm_load
@prev sm_quit
Shortcut key: none
This menu option toggles whether the progress window is displayed when files
are being processed. If the tick symbol is shown by the option then the
progress window will not be shown.
The initial setting of this can be set using the @{"QUIET" link wb_quiet} tooltype.
@endnode
@node sm_load "PicIcon: Settings Menu - Load Settings"
@next sm_save
@prev sm_quiet
Shortcut key: Amiga L
An ASL file requester is displayed allowing a settings file to be selected
for loading. Pressing the OK button causes the values in the file to be
loaded into the window. This will not effect the current settings used by
PicIcon when creating images until either the @{"Save" link sw_save} or @{"Use" link sw_use} buttons are selected,
the loaded values can be removed by selecting the @{"Cancel" link sw_cancel } button.   
@endnode
@node sm_save "PicIcon: Settings Menu - Save Settings"
@next sm_saveas
@prev sm_load
Shortcut key: Amiga S
This saves the current values displayed in the window to the default settings
file S:PicIcon.config. If no Settings @{"tooltype" link wb_settings} or @{"parameter" link cli_settings} is given when
PicIcon is started then these settings will be used whenever PicIcon is run.   
@endnode
@node sm_saveas "PicIcon: Settings Menu - Save Settings As"
@next hints
@prev sm_save
Shortcut key: Amiga A
This option displays an ASL save requester allowing you to save the values
displayed in the window to a named settings file. This file can be used in
future, either by giving it as the settings @{"tooltype" link wb_settings} or @{"parameter" link cli_settings} or from
the @{"Load Settings" link sm_load } menu option, to change the values used by PicIcon to create
images.
@endnode
@node hints "PicIcon: Hints and Tips"
@next limits
@prev set_menu
If you are using a 4 colour Workbench then set PicIcon to not match
colours. There are not enough different display colours available to allow
meaningful colour matching.
If you are using an 8 colour Workbench with colour matching adjust the
palette so that you get at least one red, green, blue and yellow. This
will give PicIcon an easier job in trying to match the colours and result
in better, more recognisable icons. An example 8 colour palette is present
in the PicIcon release.
If you find that PicIcon is matching colours in an unexpected manner you 
should try and adjust the Workbench palette. If you find that PicIcon is
using changing the colour of an area in the image when a similar colour
is present in the palette try adjusting the RGB values of both palette
colours so that they are similar in intensity. An example of this would
be a dark green area on the image being represented by a dark brown area
on the icon when a light green is present in the palette. To solve this
problem make the green a little darker until the correct result is 
obtained.
For complex images try and make the icon image as large as possible. Small
icons of complex pictures look cluttered and are not easily recognisable.
@endnode
@node wb3 "Notes for Workbench 3.0"
@next limits
@prev hints
With Workbench 3.0 a number of changes were introduced regarding the way
in which colours are defined and used by Workbench. This can result in
some odd behaviour from PicIcon.
For correct operation under Workbench 3.0 you should either create only
4 colour Icons, in which case PicIcon will use the first 4 colours defined
by Workbench, or use an 8 colour screen mode with 8 colour icons.
If you try and create 8 colour icons using a screen mode with more than 8
colours then PicIcon may have problems trying to match with colours 5 to 8.
@endnode
@node limits "PicIcon Limitations"
@next history
@prev wb3
PicIcon will process all ILBM files with 6 or fewer planes, including HAM
and extra-half brite files. In addition PicIcon will process 24 bit ILBM
files. All ANIM files made up of images of any of the above formats will
also be processed.
This version of PicIcon will not process 256 colour or HAM8 files. Also it
will not process 24bit DEEP, NewTek 21bit, HAME or DCTV files.
@endnode
@node history "PicIcon Change History"
@prev limits
@next bugs
  Version        Change description
   1.03        - The Workbench colours are now read directly from the screen
                 rather than the preferences file. This corrected operation
                 under Workbench 3.0. See @{ "Notes for Workbench 3.0" link wb3} above.
                 PicIcon now notices when the palette is changed and updates
                 it's internal colour table accordingly.
                 
   1.02        - The tooltype array used to create the new icon was not NULL
                 terminated causing random errors when trying to add tooltypes
                 to an icon, including infinite updating and spurious tooltype
                 entries. Fixed.
   1.01        - Changed name of button used to create a new tooltype from
                 @{b}Add@{ub} to @{b}New@{ub} to be consistent with other programs.
               - If PicIcon expects to be able to match colours but there
                 is no CMAP chunk in the ILBM IFF form then a warning is
                 displayed before the file is processed.
   1.00        - Initial Release.
@endnode
@node bugs "PicIcon Bug reports"
@next ack
@prev history
If you find a bug in PicIcon or have a file that it will not process then
please contact;
   Michael J. Sheppard
   163 Sapgate Lane,
   Thornton.
   Bradford.
   BD13 3DY.
   United Kingdom
      
   Email: mick@genasys.co.uk
If the problem is one where you cannot process a file please include details
of the format of the file, if known, and the software used to produce it. The
more information you provide me with the more likely I am to be able to find
an answer.
@endnode
@node ack Acknowledgments "PicIcon Acknowledgements"
@prev bugs
PicIcon was written and tested on an unaccelerated Commodore Amiga A2000 with
a GVP Series II SCSI controller card and 52MB Quantum Hard Disk.
PicIcon was developed using SAS/C 5.10 and the Commodore V37 Native
Developer Kit.
The windows were designed using GadToolsBox 2.0. Thanks to Jan van den Baard
of Jaba Development for this very useful product.
Thanks to David Sheppard for testing and suggestions.   
@endnode